{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "%matplotlib inline"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n# Constrained Layout Guide\n\n\nHow to use constrained-layout to fit plots within your figure cleanly.\n\n*constrained_layout* automatically adjusts subplots and decorations like\nlegends and colorbars so that they fit in the figure window while still\npreserving, as best they can, the logical layout requested by the user.\n\n*constrained_layout* is similar to\n:doc:`tight_layout</tutorials/intermediate/tight_layout_guide>`,\nbut uses a constraint solver to determine the size of axes that allows\nthem to fit.\n\n*constrained_layout* needs to be activated before any axes are added to\na figure. Two ways of doing so are\n\n* using the respective argument to :func:`~.pyplot.subplots` or\n  :func:`~.pyplot.figure`, e.g.::\n\n      plt.subplots(constrained_layout=True)\n\n* activate it via `rcParams<matplotlib-rcparams>`, like::\n\n      plt.rcParams['figure.constrained_layout.use'] = True\n\nThose are described in detail throughout the following sections.\n\n<div class=\"alert alert-danger\"><h4>Warning</h4><p>Currently Constrained Layout is **experimental**.  The\n    behaviour and API are subject to change, or the whole functionality\n    may be removed without a deprecation period.  If you *require* your\n    plots to be absolutely reproducible, get the Axes positions after\n    running Constrained Layout and use ``ax.set_position()`` in your code\n    with ``constrained_layout=False``.</p></div>\n\nSimple Example\n==============\n\nIn Matplotlib, the location of axes (including subplots) are specified in\nnormalized figure coordinates. It can happen that your axis labels or\ntitles (or sometimes even ticklabels) go outside the figure area, and are thus\nclipped.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "# sphinx_gallery_thumbnail_number = 18\n\n\nimport matplotlib.pyplot as plt\nimport matplotlib.colors as mcolors\nimport matplotlib.gridspec as gridspec\nimport numpy as np\n\n\nplt.rcParams['savefig.facecolor'] = \"0.8\"\nplt.rcParams['figure.figsize'] = 4.5, 4.\n\n\ndef example_plot(ax, fontsize=12, nodec=False):\n    ax.plot([1, 2])\n\n    ax.locator_params(nbins=3)\n    if not nodec:\n        ax.set_xlabel('x-label', fontsize=fontsize)\n        ax.set_ylabel('y-label', fontsize=fontsize)\n        ax.set_title('Title', fontsize=fontsize)\n    else:\n        ax.set_xticklabels('')\n        ax.set_yticklabels('')\n\n\nfig, ax = plt.subplots(constrained_layout=False)\nexample_plot(ax, fontsize=24)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To prevent this, the location of axes needs to be adjusted. For\nsubplots, this can be done by adjusting the subplot params\n(`howto-subplots-adjust`). However, specifying your figure with the\n``constrained_layout=True`` kwarg will do the adjusting automatically.\n\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "fig, ax = plt.subplots(constrained_layout=True)\nexample_plot(ax, fontsize=24)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When you have multiple subplots, often you see labels of different\naxes overlapping each other.\n\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "fig, axs = plt.subplots(2, 2, constrained_layout=False)\nfor ax in axs.flat:\n    example_plot(ax)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Specifying ``constrained_layout=True`` in the call to ``plt.subplots``\ncauses the layout to be properly constrained.\n\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "fig, axs = plt.subplots(2, 2, constrained_layout=True)\nfor ax in axs.flat:\n    example_plot(ax)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Colorbars\n=========\n\nIf you create a colorbar with the :func:`~matplotlib.pyplot.colorbar`\ncommand you need to make room for it.  ``constrained_layout`` does this\nautomatically.  Note that if you specify ``use_gridspec=True`` it will be\nignored because this option is made for improving the layout via\n``tight_layout``.\n\n<div class=\"alert alert-info\"><h4>Note</h4><p>For the `~.axes.Axes.pcolormesh` kwargs (``pc_kwargs``) we use a\n  dictionary. Below we will assign one colorbar to a number of axes each\n  containing a `~.cm.ScalarMappable`; specifying the norm and colormap\n  ensures the colorbar is accurate for all the axes.</p></div>\n\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "arr = np.arange(100).reshape((10, 10))\nnorm = mcolors.Normalize(vmin=0., vmax=100.)\n# see note above: this makes all pcolormesh calls consistent:\npc_kwargs = {'rasterized': True, 'cmap': 'viridis', 'norm': norm}\nfig, ax = plt.subplots(figsize=(4, 4), constrained_layout=True)\nim = ax.pcolormesh(arr, **pc_kwargs)\nfig.colorbar(im, ax=ax, shrink=0.6)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you specify a list of axes (or other iterable container) to the\n``ax`` argument of ``colorbar``, constrained_layout will take space from\nthe specified axes.\n\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "fig, axs = plt.subplots(2, 2, figsize=(4, 4), constrained_layout=True)\nfor ax in axs.flat:\n    im = ax.pcolormesh(arr, **pc_kwargs)\nfig.colorbar(im, ax=axs, shrink=0.6)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you specify a list of axes from inside a grid of axes, the colorbar\nwill steal space appropriately, and leave a gap, but all subplots will\nstill be the same size.\n\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "fig, axs = plt.subplots(3, 3, figsize=(4, 4), constrained_layout=True)\nfor ax in axs.flat:\n    im = ax.pcolormesh(arr, **pc_kwargs)\nfig.colorbar(im, ax=axs[1:, ][:, 1], shrink=0.8)\nfig.colorbar(im, ax=axs[:, -1], shrink=0.6)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that there is a bit of a subtlety when specifying a single axes\nas the parent.  In the following, it might be desirable and expected\nfor the colorbars to line up, but they don't because the colorbar paired\nwith the bottom axes is tied to the subplotspec of the axes, and hence\nshrinks when the gridspec-level colorbar is added.\n\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "fig, axs = plt.subplots(3, 1, figsize=(4, 4), constrained_layout=True)\nfor ax in axs[:2]:\n    im = ax.pcolormesh(arr, **pc_kwargs)\nfig.colorbar(im, ax=axs[:2], shrink=0.6)\nim = axs[2].pcolormesh(arr, **pc_kwargs)\nfig.colorbar(im, ax=axs[2], shrink=0.6)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The API to make a single-axes behave like a list of axes is to specify\nit as a list (or other iterable container), as below:\n\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "fig, axs = plt.subplots(3, 1, figsize=(4, 4), constrained_layout=True)\nfor ax in axs[:2]:\n    im = ax.pcolormesh(arr, **pc_kwargs)\nfig.colorbar(im, ax=axs[:2], shrink=0.6)\nim = axs[2].pcolormesh(arr, **pc_kwargs)\nfig.colorbar(im, ax=[axs[2]], shrink=0.6)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Suptitle\n=========\n\n``constrained_layout`` can also make room for `~.figure.Figure.suptitle`.\n\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "fig, axs = plt.subplots(2, 2, figsize=(4, 4), constrained_layout=True)\nfor ax in axs.flat:\n    im = ax.pcolormesh(arr, **pc_kwargs)\nfig.colorbar(im, ax=axs, shrink=0.6)\nfig.suptitle('Big Suptitle')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Legends\n=======\n\nLegends can be placed outside of their parent axis.\nConstrained-layout is designed to handle this for :meth:`.Axes.legend`.\nHowever, constrained-layout does *not* handle legends being created via\n:meth:`.Figure.legend` (yet).\n\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "fig, ax = plt.subplots(constrained_layout=True)\nax.plot(np.arange(10), label='This is a plot')\nax.legend(loc='center left', bbox_to_anchor=(0.8, 0.5))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "However, this will steal space from a subplot layout:\n\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "fig, axs = plt.subplots(1, 2, figsize=(4, 2), constrained_layout=True)\naxs[0].plot(np.arange(10))\naxs[1].plot(np.arange(10), label='This is a plot')\naxs[1].legend(loc='center left', bbox_to_anchor=(0.8, 0.5))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In order for a legend or other artist to *not* steal space\nfrom the subplot layout, we can ``leg.set_in_layout(False)``.\nOf course this can mean the legend ends up\ncropped, but can be useful if the plot is subsequently called\nwith ``fig.savefig('outname.png', bbox_inches='tight')``.  Note,\nhowever, that the legend's ``get_in_layout`` status will have to be\ntoggled again to make the saved file work, and we must manually\ntrigger a draw if we want constrained_layout to adjust the size\nof the axes before printing.\n\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "fig, axs = plt.subplots(1, 2, figsize=(4, 2), constrained_layout=True)\n\naxs[0].plot(np.arange(10))\naxs[1].plot(np.arange(10), label='This is a plot')\nleg = axs[1].legend(loc='center left', bbox_to_anchor=(0.8, 0.5))\nleg.set_in_layout(False)\n# trigger a draw so that constrained_layout is executed once\n# before we turn it off when printing....\nfig.canvas.draw()\n# we want the legend included in the bbox_inches='tight' calcs.\nleg.set_in_layout(True)\n# we don't want the layout to change at this point.\nfig.set_constrained_layout(False)\nfig.savefig('CL01.png', bbox_inches='tight', dpi=100)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The saved file looks like:\n\n![](/_static/constrained_layout/CL01.png)\n\n   :align: center\n\nA better way to get around this awkwardness is to simply\nuse the legend method provided by `.Figure.legend`:\n\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "fig, axs = plt.subplots(1, 2, figsize=(4, 2), constrained_layout=True)\naxs[0].plot(np.arange(10))\nlines = axs[1].plot(np.arange(10), label='This is a plot')\nlabels = [l.get_label() for l in lines]\nleg = fig.legend(lines, labels, loc='center left',\n                 bbox_to_anchor=(0.8, 0.5), bbox_transform=axs[1].transAxes)\nfig.savefig('CL02.png', bbox_inches='tight', dpi=100)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The saved file looks like:\n\n![](/_static/constrained_layout/CL02.png)\n\n   :align: center\n\n\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Padding and Spacing\n===================\n\nFor constrained_layout, we have implemented a padding around the edge of\neach axes.  This padding sets the distance from the edge of the plot,\nand the minimum distance between adjacent plots.  It is specified in\ninches by the keyword arguments ``w_pad`` and ``h_pad`` to the function\n`~.figure.Figure.set_constrained_layout_pads`:\n\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "fig, axs = plt.subplots(2, 2, constrained_layout=True)\nfor ax in axs.flat:\n    example_plot(ax, nodec=True)\n    ax.set_xticklabels('')\n    ax.set_yticklabels('')\nfig.set_constrained_layout_pads(w_pad=4./72., h_pad=4./72.,\n        hspace=0., wspace=0.)\n\nfig, axs = plt.subplots(2, 2, constrained_layout=True)\nfor ax in axs.flat:\n    example_plot(ax, nodec=True)\n    ax.set_xticklabels('')\n    ax.set_yticklabels('')\nfig.set_constrained_layout_pads(w_pad=2./72., h_pad=2./72.,\n        hspace=0., wspace=0.)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Spacing between subplots is set by ``wspace`` and ``hspace``. There are\nspecified as a fraction of the size of the subplot group as a whole.\nIf the size of the figure is changed, then these spaces change in\nproportion.  Note in the blow how the space at the edges doesn't change from\nthe above, but the space between subplots does.\n\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "fig, axs = plt.subplots(2, 2, constrained_layout=True)\nfor ax in axs.flat:\n    example_plot(ax, nodec=True)\n    ax.set_xticklabels('')\n    ax.set_yticklabels('')\nfig.set_constrained_layout_pads(w_pad=2./72., h_pad=2./72.,\n        hspace=0.2, wspace=0.2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Spacing with colorbars\n-----------------------\n\nColorbars will be placed ``wspace`` and ``hsapce`` apart from other\nsubplots. The padding between the colorbar and the axis it is\nattached to will never be less than ``w_pad`` (for a vertical colorbar)\nor ``h_pad`` (for a horizontal colorbar). Note the use of the ``pad`` kwarg\nhere in the ``colorbar`` call.  It defaults to 0.02 of the size\nof the axis it is attached to.\n\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "fig, axs = plt.subplots(2, 2, constrained_layout=True)\nfor ax in axs.flat:\n    pc = ax.pcolormesh(arr, **pc_kwargs)\n    fig.colorbar(pc, ax=ax, shrink=0.6, pad=0)\n    ax.set_xticklabels('')\n    ax.set_yticklabels('')\nfig.set_constrained_layout_pads(w_pad=2./72., h_pad=2./72.,\n        hspace=0.2, wspace=0.2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the above example, the colorbar will not ever be closer than 2 pts to\nthe plot, but if we want it a bit further away, we can specify its value\nfor ``pad`` to be non-zero.\n\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "fig, axs = plt.subplots(2, 2, constrained_layout=True)\nfor ax in axs.flat:\n    pc = ax.pcolormesh(arr, **pc_kwargs)\n    fig.colorbar(im, ax=ax, shrink=0.6, pad=0.05)\n    ax.set_xticklabels('')\n    ax.set_yticklabels('')\nfig.set_constrained_layout_pads(w_pad=2./72., h_pad=2./72.,\n        hspace=0.2, wspace=0.2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "rcParams\n========\n\nThere are five `rcParams<matplotlib-rcparams>` that can be set,\neither in a script or in the `matplotlibrc` file.\nThey all have the prefix ``figure.constrained_layout``:\n\n- ``use``: Whether to use constrained_layout. Default is False\n- ``w_pad``, ``h_pad``:    Padding around axes objects.\n   Float representing inches.  Default is 3./72. inches (3 pts)\n- ``wspace``, ``hspace``:  Space between subplot groups.\n   Float representing a fraction of the subplot widths being separated.\n   Default is 0.02.\n\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "plt.rcParams['figure.constrained_layout.use'] = True\nfig, axs = plt.subplots(2, 2, figsize=(3, 3))\nfor ax in axs.flat:\n    example_plot(ax)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Use with GridSpec\n=================\n\nconstrained_layout is meant to be used\nwith :func:`~matplotlib.figure.Figure.subplots` or\n:func:`~matplotlib.gridspec.GridSpec` and\n:func:`~matplotlib.figure.Figure.add_subplot`.\n\nNote that in what follows ``constrained_layout=True``\n\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "fig = plt.figure()\n\ngs1 = gridspec.GridSpec(2, 1, figure=fig)\nax1 = fig.add_subplot(gs1[0])\nax2 = fig.add_subplot(gs1[1])\n\nexample_plot(ax1)\nexample_plot(ax2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "More complicated gridspec layouts are possible.  Note here we use the\nconvenience functions ``add_gridspec`` and ``subgridspec``.\n\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "fig = plt.figure()\n\ngs0 = fig.add_gridspec(1, 2)\n\ngs1 = gs0[0].subgridspec(2, 1)\nax1 = fig.add_subplot(gs1[0])\nax2 = fig.add_subplot(gs1[1])\n\nexample_plot(ax1)\nexample_plot(ax2)\n\ngs2 = gs0[1].subgridspec(3, 1)\n\nfor ss in gs2:\n    ax = fig.add_subplot(ss)\n    example_plot(ax)\n    ax.set_title(\"\")\n    ax.set_xlabel(\"\")\n\nax.set_xlabel(\"x-label\", fontsize=12)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that in the above the left and columns don't have the same vertical\nextent.  If we want the top and bottom of the two grids to line up then\nthey need to be in the same gridspec:\n\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "fig = plt.figure()\n\ngs0 = fig.add_gridspec(6, 2)\n\nax1 = fig.add_subplot(gs0[:3, 0])\nax2 = fig.add_subplot(gs0[3:, 0])\n\nexample_plot(ax1)\nexample_plot(ax2)\n\nax = fig.add_subplot(gs0[0:2, 1])\nexample_plot(ax)\nax = fig.add_subplot(gs0[2:4, 1])\nexample_plot(ax)\nax = fig.add_subplot(gs0[4:, 1])\nexample_plot(ax)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This example uses two gridspecs to have the colorbar only pertain to\none set of pcolors.  Note how the left column is wider than the\ntwo right-hand columns because of this.  Of course, if you wanted the\nsubplots to be the same size you only needed one gridspec.\n\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "def docomplicated(suptitle=None):\n    fig = plt.figure()\n    gs0 = fig.add_gridspec(1, 2, figure=fig, width_ratios=[1., 2.])\n    gsl = gs0[0].subgridspec(2, 1)\n    gsr = gs0[1].subgridspec(2, 2)\n\n    for gs in gsl:\n        ax = fig.add_subplot(gs)\n        example_plot(ax)\n    axs = []\n    for gs in gsr:\n        ax = fig.add_subplot(gs)\n        pcm = ax.pcolormesh(arr, **pc_kwargs)\n        ax.set_xlabel('x-label')\n        ax.set_ylabel('y-label')\n        ax.set_title('title')\n\n        axs += [ax]\n    fig.colorbar(pcm, ax=axs)\n    if suptitle is not None:\n        fig.suptitle(suptitle)\n\ndocomplicated()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Manually setting axes positions\n================================\n\nThere can be good reasons to manually set an axes position.  A manual call\nto `~.axes.Axes.set_position` will set the axes so constrained_layout has\nno effect on it anymore. (Note that constrained_layout still leaves the\nspace for the axes that is moved).\n\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "fig, axs = plt.subplots(1, 2)\nexample_plot(axs[0], fontsize=12)\naxs[1].set_position([0.2, 0.2, 0.4, 0.4])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you want an inset axes in data-space, you need to manually execute the\nlayout using ``fig.execute_constrained_layout()`` call.  The inset figure\nwill then be properly positioned.  However, it will not be properly\npositioned if the size of the figure is subsequently changed.  Similarly,\nif the figure is printed to another backend, there may be slight changes\nof location due to small differences in how the backends render fonts.\n\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "from matplotlib.transforms import Bbox\n\nfig, axs = plt.subplots(1, 2)\nexample_plot(axs[0], fontsize=12)\nfig.execute_constrained_layout()\n# put into data-space:\nbb_data_ax2 = Bbox.from_bounds(0.5, 1., 0.2, 0.4)\ndisp_coords = axs[0].transData.transform(bb_data_ax2)\nfig_coords_ax2 = fig.transFigure.inverted().transform(disp_coords)\nbb_ax2 = Bbox(fig_coords_ax2)\nax2 = fig.add_axes(bb_ax2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Manually turning off ``constrained_layout``\n===========================================\n\n``constrained_layout`` usually adjusts the axes positions on each draw\nof the figure.  If you want to get the spacing provided by\n``constrained_layout`` but not have it update, then do the initial\ndraw and then call ``fig.set_constrained_layout(False)``.\nThis is potentially useful for animations where the tick labels may\nchange length.\n\nNote that ``constrained_layout`` is turned off for ``ZOOM`` and ``PAN``\nGUI events for the backends that use the toolbar.  This prevents the\naxes from changing position during zooming and panning.\n\n\nLimitations\n========================\n\nIncompatible functions\n----------------------\n\n``constrained_layout`` will not work on subplots\ncreated via the `subplot` command.  The reason is that each of these\ncommands creates a separate `GridSpec` instance and ``constrained_layout``\nuses (nested) gridspecs to carry out the layout.  So the following fails\nto yield a nice layout:\n\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "fig = plt.figure()\n\nax1 = plt.subplot(221)\nax2 = plt.subplot(223)\nax3 = plt.subplot(122)\n\nexample_plot(ax1)\nexample_plot(ax2)\nexample_plot(ax3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Of course that layout is possible using a gridspec:\n\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "fig = plt.figure()\ngs = fig.add_gridspec(2, 2)\n\nax1 = fig.add_subplot(gs[0, 0])\nax2 = fig.add_subplot(gs[1, 0])\nax3 = fig.add_subplot(gs[:, 1])\n\nexample_plot(ax1)\nexample_plot(ax2)\nexample_plot(ax3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Similarly,\n:func:`~matplotlib.pyplot.subplot2grid` doesn't work for the same reason:\neach call creates a different parent gridspec.\n\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "fig = plt.figure()\n\nax1 = plt.subplot2grid((3, 3), (0, 0))\nax2 = plt.subplot2grid((3, 3), (0, 1), colspan=2)\nax3 = plt.subplot2grid((3, 3), (1, 0), colspan=2, rowspan=2)\nax4 = plt.subplot2grid((3, 3), (1, 2), rowspan=2)\n\nexample_plot(ax1)\nexample_plot(ax2)\nexample_plot(ax3)\nexample_plot(ax4)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The way to make this plot compatible with ``constrained_layout`` is again\nto use ``gridspec`` directly\n\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "fig = plt.figure()\ngs = fig.add_gridspec(3, 3)\n\nax1 = fig.add_subplot(gs[0, 0])\nax2 = fig.add_subplot(gs[0, 1:])\nax3 = fig.add_subplot(gs[1:, 0:2])\nax4 = fig.add_subplot(gs[1:, -1])\n\nexample_plot(ax1)\nexample_plot(ax2)\nexample_plot(ax3)\nexample_plot(ax4)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Other Caveats\n-------------\n\n* ``constrained_layout`` only considers ticklabels, axis labels, titles, and\n  legends.  Thus, other artists may be clipped and also may overlap.\n\n* It assumes that the extra space needed for ticklabels, axis labels,\n  and titles is independent of original location of axes. This is\n  often true, but there are rare cases where it is not.\n\n* There are small differences in how the backends handle rendering fonts,\n  so the results will not be pixel-identical.\n\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Debugging\n=========\n\nConstrained-layout can fail in somewhat unexpected ways.  Because it uses\na constraint solver the solver can find solutions that are mathematically\ncorrect, but that aren't at all what the user wants.  The usual failure\nmode is for all sizes to collapse to their smallest allowable value. If\nthis happens, it is for one of two reasons:\n\n1. There was not enough room for the elements you were requesting to draw.\n2. There is a bug - in which case open an issue at\n   https://github.com/matplotlib/matplotlib/issues.\n\nIf there is a bug, please report with a self-contained example that does\nnot require outside data or dependencies (other than numpy).\n\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notes on the algorithm\n======================\n\nThe algorithm for the constraint is relatively straightforward, but\nhas some complexity due to the complex ways we can layout a figure.\n\nFigure layout\n-------------\n\nFigures are laid out in a hierarchy:\n\n1. Figure: ``fig = plt.figure()``\n\n  a. Gridspec ``gs0 = gridspec.GridSpec(1, 2, figure=fig)``\n\n      i. Subplotspec: ``ss = gs[0, 0]``\n\n         1. Axes: ``ax0 = fig.add_subplot(ss)``\n\n      ii. Subplotspec: ``ss = gs[0, 1]``\n\n         1. Gridspec: ``gsR = gridspec.GridSpecFromSubplotSpec(2, 1, ss)``\n\n            - Subplotspec: ``ss = gsR[0, 0]``\n\n               - Axes: ``axR0 = fig.add_subplot(ss)``\n\n            - Subplotspec: ``ss = gsR[1, 0]``\n\n               - Axes: ``axR1 = fig.add_subplot(ss)``\n\nEach item has a layoutbox associated with it. The nesting of gridspecs\ncreated with `.GridSpecFromSubplotSpec` can be arbitrarily deep.\n\nEach `~matplotlib.axes.Axes` has *two* layoutboxes.  The first one,\n``ax._layoutbox`` represents the outside of the Axes and all its\ndecorations (i.e. ticklabels,axis labels, etc.).\nThe second layoutbox corresponds to the Axes' ``ax.position``, which sets\nwhere in the figure the spines are placed.\n\nWhy so many stacked containers?  Ideally, all that would be needed are the\nAxes layout boxes. For the Gridspec case, a container is\nneeded if the Gridspec is nested via `.GridSpecFromSubplotSpec`.  At the\ntop level, it is desirable for symmetry, but it also makes room for\n`~.Figure.suptitle`.\n\nFor the Subplotspec/Axes case, Axes often have colorbars or other\nannotations that need to be packaged inside the Subplotspec, hence the\nneed for the outer layer.\n\n\nSimple case: one Axes\n---------------------\n\nFor a single Axes the layout is straight forward.  The Figure and\nouter Gridspec layoutboxes coincide.  The Subplotspec and Axes\nboxes also coincide because the Axes has no colorbar.  Note\nthe difference between the red ``pos`` box and the green ``ax`` box\nis set by the size of the decorations around the Axes.\n\nIn the code, this is accomplished by the entries in\n``do_constrained_layout()`` like::\n\n    ax._poslayoutbox.edit_left_margin_min(-bbox.x0 + pos.x0 + w_padt)\n\n\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "from matplotlib._layoutbox import plot_children\n\nfig, ax = plt.subplots(constrained_layout=True)\nexample_plot(ax, fontsize=24)\nplot_children(fig, fig._layoutbox, printit=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Simple case: two Axes\n---------------------\nFor this case, the Axes layoutboxes and the Subplotspec boxes still\nco-incide.  However, because the decorations in the right-hand plot are so\nmuch smaller than the left-hand, so the right-hand layoutboxes are smaller.\n\nThe Subplotspec boxes are laid out in the code in the subroutine\n``arange_subplotspecs()``, which simply checks the subplotspecs in the code\nagainst one another and stacks them appropriately.\n\nThe two ``pos`` axes are lined up.  Because they have the same\nminimum row, they are lined up at the top. Because\nthey have the same maximum row they are lined up at the bottom.  In the\ncode this is accomplished via the calls to ``layoutbox.align``.  If\nthere was more than one row, then the same horizontal alignment would\noccur between the rows.\n\nThe two ``pos`` axes are given the same width because the subplotspecs\noccupy the same number of columns.  This is accomplished in the code where\n``dcols0`` is compared to ``dcolsC``.  If they are equal, then their widths\nare constrained to be equal.\n\nWhile it is a bit subtle in this case, note that the division between the\nSubplotspecs is *not* centered, but has been moved to the right to make\nspace for the larger labels on the left-hand plot.\n\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "fig, ax = plt.subplots(1, 2, constrained_layout=True)\nexample_plot(ax[0], fontsize=32)\nexample_plot(ax[1], fontsize=8)\nplot_children(fig, fig._layoutbox, printit=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Two Axes and colorbar\n---------------------\n\nAdding a colorbar makes it clear why the Subplotspec layoutboxes must\nbe different from the axes layoutboxes.  Here we see the left-hand\nsubplotspec has more room to accommodate the `~.Figure.colorbar`, and\nthat there are two green ``ax`` boxes inside the ``ss`` box.\n\nNote that the width of the ``pos`` boxes is still the same because of the\nconstraint on their widths because their subplotspecs occupy the same\nnumber of columns (one in this example).\n\nThe colorbar layout logic is contained in `~matplotlib.colorbar.make_axes`\nwhich calls ``_constrained_layout.layoutcolorbarsingle()``\nfor cbars attached to a single axes, and\n``_constrained_layout.layoutcolorbargridspec()`` if the colorbar is\nassociated with a gridspec.\n\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "fig, ax = plt.subplots(1, 2, constrained_layout=True)\nim = ax[0].pcolormesh(arr, **pc_kwargs)\nfig.colorbar(im, ax=ax[0], shrink=0.6)\nim = ax[1].pcolormesh(arr, **pc_kwargs)\nplot_children(fig, fig._layoutbox, printit=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Colorbar associated with a Gridspec\n-----------------------------------\n\nThis example shows the Subplotspec layoutboxes being made smaller by\na colorbar layoutbox.  The size of the colorbar layoutbox is\nset to be ``shrink`` smaller than the vertical extent of the ``pos``\nlayoutboxes in the gridspec, and it is made to be centered between\nthose two points.\n\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "fig, axs = plt.subplots(2, 2, constrained_layout=True)\nfor ax in axs.flat:\n    im = ax.pcolormesh(arr, **pc_kwargs)\nfig.colorbar(im, ax=axs, shrink=0.6)\nplot_children(fig, fig._layoutbox, printit=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Uneven sized Axes\n-----------------\n\nThere are two ways to make axes have an uneven size in a\nGridspec layout, either by specifying them to cross Gridspecs rows\nor columns, or by specifying width and height ratios.\n\nThe first method is used here.  The constraint that makes the heights\nbe correct is in the code where ``drowsC < drows0`` which in\nthis case would be 1 is less than 2.  So we constrain the\nheight of the 1-row Axes to be less than half the height of the\n2-row Axes.\n\n<div class=\"alert alert-info\"><h4>Note</h4><p>This algorithm can be wrong if the decorations attached to the smaller\n   axes are very large, so there is an unaccounted-for edge case.</p></div>\n\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "fig = plt.figure(constrained_layout=True)\ngs = gridspec.GridSpec(2, 2, figure=fig)\nax = fig.add_subplot(gs[:, 0])\nim = ax.pcolormesh(arr, **pc_kwargs)\nax = fig.add_subplot(gs[0, 1])\nim = ax.pcolormesh(arr, **pc_kwargs)\nax = fig.add_subplot(gs[1, 1])\nim = ax.pcolormesh(arr, **pc_kwargs)\nplot_children(fig, fig._layoutbox, printit=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Height and width ratios are accommodated with the same part of\nthe code with the smaller axes always constrained to be less in size\nthan the larger.\n\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "fig = plt.figure(constrained_layout=True)\ngs = gridspec.GridSpec(3, 2, figure=fig,\n    height_ratios=[1., 0.5, 1.5],\n    width_ratios=[1.2, 0.8])\nax = fig.add_subplot(gs[:2, 0])\nim = ax.pcolormesh(arr, **pc_kwargs)\nax = fig.add_subplot(gs[2, 0])\nim = ax.pcolormesh(arr, **pc_kwargs)\nax = fig.add_subplot(gs[0, 1])\nim = ax.pcolormesh(arr, **pc_kwargs)\nax = fig.add_subplot(gs[1:, 1])\nim = ax.pcolormesh(arr, **pc_kwargs)\nplot_children(fig, fig._layoutbox, printit=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Empty gridspec slots\n--------------------\n\nThe final piece of the code that has not been explained is what happens if\nthere is an empty gridspec opening.  In that case a fake invisible axes is\nadded and we proceed as before.  The empty gridspec has no decorations, but\nthe axes position in made the same size as the occupied Axes positions.\n\nThis is done at the start of\n``_constrained_layout.do_constrained_layout()`` (``hassubplotspec``).\n\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "fig = plt.figure(constrained_layout=True)\ngs = gridspec.GridSpec(1, 3, figure=fig)\nax = fig.add_subplot(gs[0])\nim = ax.pcolormesh(arr, **pc_kwargs)\nax = fig.add_subplot(gs[-1])\nim = ax.pcolormesh(arr, **pc_kwargs)\nplot_children(fig, fig._layoutbox, printit=False)\nplt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Other notes\n-----------\n\nThe layout is called only once.  This is OK if the original layout was\npretty close (which it should be in most cases).  However, if the layout\nchanges a lot from the default layout then the decorators can change size.\nIn particular the x and ytick labels can change.  If this happens, then\nwe should probably call the whole routine twice.\n\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}
